.TH std::setvbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::setvbuf \- std::setvbuf

.SH Synopsis
   Defined in header <cstdio>
   int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );

   Changes the buffering mode of the given file stream stream as indicated by the
   argument mode. In addition,

     * If buffer is a null pointer, resizes the internal buffer to size.
     * If buffer is not a null pointer, instructs the stream to use the user-provided
       buffer of size size beginning at buffer. The stream must be closed (with
       std::fclose) before the lifetime of the array pointed to by buffer ends. The
       contents of the array after a successful call to std::setvbuf are indeterminate
       and any attempt to use it is undefined behavior.

.SH Parameters

   stream - the file stream to set the buffer to
   buffer - pointer to a buffer for the stream to use or null pointer to change size
            and mode only
            buffering mode to use. It can be one of the following values:

   mode   - _IOFBF full buffering
            _IOLBF line buffering
            _IONBF no buffering
   size   - size of the buffer

.SH Return value

   0 on success or nonzero on failure.

.SH Notes

   This function may only be used after stream has been associated with an open file,
   but before any other operation (other than a failed call to
   std::setbuf/std::setvbuf).

   Not all size bytes will necessarily be used for buffering: the actual buffer size is
   usually rounded down to a multiple of 2, a multiple of page size, etc.

   On many implementations, line buffering is only available for terminal input
   streams.

   A common error is setting the buffer of stdin or stdout to an array whose lifetime
   ends before the program terminates:

 int main()
 {
     char buf[BUFSIZ];
     std::setbuf(stdin, buf);
 } // lifetime of buf ends, undefined behavior

   The default buffer size BUFSIZ is expected to be the most efficient buffer size for
   file I/O on the implementation, but POSIX fstat often provides a better estimate.

.SH Example

   One use case for changing buffer size is when a better size is known.


// Run this code

 #include <cstdio>
 #include <cstdlib>
 #include <iostream>
 #include <sys/stat.h>

 int main()
 {
     std::FILE* fp = std::fopen("/tmp/test.txt", "w+");
     if (!fp)
     {
         std::perror("fopen");
         return EXIT_FAILURE;
     }

     struct stat stats;
     if (fstat(fileno(fp), &stats) == -1) // POSIX only
     {
         std::perror("fstat");
         return EXIT_FAILURE;
     }

     std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
               << stats.st_blksize << '\\n';
     if (std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0)
     {
         std::perror("setvbuf failed"); // POSIX version sets errno
         return EXIT_FAILURE;
     }

     // Read entire file: use truss/strace to observe the read(2) syscalls used
     for (int ch; (ch = std::fgetc(fp)) != EOF;)
     {}

     std::fclose(fp);
     return EXIT_SUCCESS;
 }

.SH Possible output:

 BUFSIZ is 8192, but optimal block size is 65536

.SH See also

   setbuf    sets the buffer for a file stream
             \fI(function)\fP
   setbuf    provides user-supplied buffer or turns this filebuf unbuffered
   \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf<CharT,Traits>)\fP

   C documentation for
   setvbuf
